package com.docmgmt.mvp.ragflow.dto;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import jakarta.validation.constraints.Size;

/**
 * 创建对话会话请求 DTO
 * 
 * 用于调用 RAGFlow 的 POST /api/v1/chats/{chat_id}/sessions 接口
 * 
 * 对话会话（Session）的作用：
 * - 管理多轮对话的上下文
 * - 隔离不同主题的对话
 * - 方便查看和管理对话历史
 * 
 * 使用场景：
 * - 用户开始新的对话主题时，创建新会话
 * - 用户想要清空对话历史时，创建新会话
 * - 系统自动创建会话（如果用户发送消息时未指定会话 ID）
 * 
 * 使用示例：
 * <pre>
 * // 创建命名会话
 * CreateSessionRequest request = CreateSessionRequest.builder()
 *     .name("讨论 RAGFlow 架构")
 *     .build();
 * 
 * // 创建匿名会话（使用默认名称）
 * CreateSessionRequest request = CreateSessionRequest.builder()
 *     .build();
 * </pre>
 * 
 * @author Dora
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CreateSessionRequest {

    /**
     * 会话名称（可选）
     * 
     * 用于标识和区分不同的对话会话。
     * 
     * 行为：
     * - 如果传值：使用指定的名称
     * - 如果不传：系统自动生成默认名称（如 "会话 1"、"会话 2"）
     * 
     * 限制：
     * - 长度范围：1-255 字符
     * - 支持中文、英文、数字、特殊字符
     * - 不能包含换行符
     * 
     * 命名建议：
     * - 使用描述性名称，便于后续查找
     * - 包含对话主题或时间信息
     * 
     * 示例：
     * - "讨论 RAGFlow 架构"
     * - "产品需求分析 - 2025-01-15"
     * - "技术问题咨询"
     * - "文档总结"
     * 
     * 注意事项：
     * - 会话名称可以重复（系统通过 ID 区分）
     * - 创建后可以通过更新接口修改名称
     * - 删除会话会同时删除该会话的所有对话历史
     */
    @Size(max = 255, message = "会话名称长度不能超过 255 字符")
    private String name;

    /**
     * 获取会话名称（非空安全）
     * 
     * 如果 name 为 null 或空字符串，返回默认名称。
     * 
     * @return 会话名称
     */
    public String getNameOrDefault() {
        if (name == null || name.trim().isEmpty()) {
            return "新会话";
        }
        return name.trim();
    }
}

